Cream of the Crop 26/Cream of the Crop 26.iso/program/qbasix.zip/Qbasix.man

Text File | 1997-07-13 | 19KB | 447 lines

         ┌───────────────────────────────────────┐
         │▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ QBASIX 2 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
         ├───────────────────────────────────────┤
         │          QBASIc eXtender         │
         │         version 2         │
         │  an external TSR library for QBasic     │
         └───────────────────────────────────────┘


    0. Legal issues
    ---------------

                 Freeware

    QBASIX is copyrighted software which is distributed as
    freeware.

    You are free to use this this software and to pass copies of it
        on to others as long as it is not for payment and not bundled
        with anything else that is for payment.



                Disclaimer

    Use of this programming package acknowledges this disclaimer of
    warranty:
    "This program is supplied as is. Hans Lunsing disclaims all
    warranties, express or implied, including, without limitation,
    the warranties of merchantability and of fitness of this program
    for any purpose. Hans Lunsing assumes no liability for damages
    direct or consequential, which may result from the use of this
    program."

                Trademarks

    All trademarks and copyrights belong to their respective holders.


    1. Why QBASIX ?
    ---------------

    QBASIC is a very useful instrument for those who want to get
    something more from their computer than only DOS is able to
    offer. Thank to its powerful development environment it is very
    easy to just build and execute a small program for a job
    otherwise a specialized program should have to be used for.

    Besides small throw-away programs you can also make bigger, well
    structured programs with it. With QBASIC Microsoft provides some
    example programs showing that very well. For that matter it is a
    match for the latest versions of the QuickBASIC compiler and
    development environment, 4 and 4.5.

    However, QuickBASIC is not for free as QBASIC, and that is
    apparent from the extra features QuickBASIC offers. For
    instance, QuickBasic can be extended easily with all sorts of
    external commands, which are included in so called libraries.
    Microsoft itself provides such a, allthough very small, library
    with QuickBASIC, including a routine with the help of which many
    different system functions can be performed: InterruptX, an
    extremely powerful addition to the language.

    It is a great pity that QBASIC must do without this. Isn't there
    nothing to do about it?     Well, it is!  That small library for
    QuickBASIC also includes the command CALL ABSOLUTE, and
    Microsoft has been so nice to bring it within reach of QBASIC
    users as an internal command of QBASIC. For QuickBASIC it really
    is a completely redundant command but for QBASIC it forms the
    back door to all sorts of beautiful extensions of the language,
    such as the already mentioned InterruptX.

    Here QBasiX TSR gets on the stage. By way of CALL ABSOLUTE it
    provides QBASIC users with a number of powerful instruments, not
    implemented in QBASIC itself.


    2. What QBASIX offers you
    -------------------------

    You will ask yourself now without doubt what one can do with
    QBasiX TSR then and if there is something for you in it. To
    quickly satisfy your curiosity here follows an overview of all
    possible instruments QBasiX TSR has to offer.

    - Performing DOS- and other system functions.
    QBasiX TSR has a command InterruptX for performing system
    functions, which can be used in the same way as the InterruptX
    command of QuickBasic. In addition there is a shortened version
    for MSDOS functions.

    - Getting and setting a command line.
    QBasiX TSR offers the possibility to provide a command line for
    the program at QBASICs startup, just as with QuickBASIC, after
    which it can be read out in the program. In the immediate window
    it can be easily changed for testing purposes.

    - Setting a termination code (error level).
    QBasiX TSR offers the possibility to set an error level before
    termination of QBASIC, which can be tested afterwards in a batch
    program with the IF [NOT] ERRORLEVEL command.

    - Reading, scanning and writing memory.
    QBasiX TSR has a number of commands which make processing memory
    easier and faster than is possible with QBASICs PEEK and POKE
    only. You can copy parts of the memory contents, scan it for a
    text string, peek a text string and peek or poke an integer
    value.

    - Getting information about the video system
    Some of QBasiX TSR' commands provide you with useful information
    about your video system, such as the type of video card, color
    or black-and-white screen, de screen mode, the number of screen
    rows and columns, the screen color in DOS etc.

    - Getting and setting some video attributes.
    You can find out if blinking text is enabled and enable or
    disable it. When you disable blinking text you can use bright
    background colors in your programs!  With that QBASIX has a
    replacement for the COLOR command, making it easier to set
    bright background colors. In addition QBASIX let you find out
    the current combination of text and background colors.

    - Processing the contents of the screen.
    QBasiX TSR provides you with a very useful command to fill a screen
    window with a certain character and/or a text color and/or a
    background color. In addition to it there are commands to save
    the contents of the entire screen or a screen window and to
    restore them again later.

    - Testing if the printer is ready for use.
    QBasiX TSR has a function for testing if the printer is ready for
    use. If not, then you can trace the cause of that with the help
    of the printer status reported as well.

    - Processing integer variables.
    QBasiX TSR lets you shift the bits of an integer variable. You can
    manipulate the two bytes of an integer in different ways, and
    you can establish easily which of two integers has the highest
    or lowest value.

    Most of these commands are written in fast and tight assembler
    code. Because they are loaded in memory outside QBASIC they
    don't seize the valuable memory provided by QBASIC to your
    program. With every assembler routine goes a basic interface
    routine with an obvious name which by means of CALL ABSOLUTE
    takes care of its execution. To be able to use an assembler
    routine you have to include its interface routine in your
    program.

    The other commands are short routines written in basic, which
    have to be included in your program normally if you want to use
    them. A number of those use QBasiX TSR' assembler routines by
    calling the interface routine going with it. Consequently this
    interface routine has to be included in your program, although
    you don't use it directly.


    3. How to use QBASIX ?
    ----------------------

    The assembler routines of QBasiX TSR - those to be called by
    means of CALL ABSOLUTE - are being loaded in memory by means of
    a separate program, QBASIX.EXE. Of course that has to be done
    before you are going to use it in QBASIC. You could include the
    command QBASIX for instance in your AUTOEXEC.BAT file.

    Once loaded in memory QBasiX TSR has a size of about 2,2 Kb. If
    you have MSDOS 5 or higher it is possible to load QBasiX TSR
    high, so that it does not seize memory for use by programs. For
    that purpose issue the command

    QBASIX /h

    You can also do it with LOADHIGH, but in that case QBasiX TSR
    needs more memory space, that is about 10 Kb, for starting up.
    If a free block of that size is not available loading QBasiX TSR
    high will not succeed, although maybe QBasiX TSR would fit well
    in one of the free blocks. So preferably use QBASIX /h.

    It is not possible to load a second copy of QBasiX TSR by
    accident. If a copy of QBasiX TSR is already in memory the
    program will recognize that and refuse to load again.

    You can also unload QBasiX TSR from memory again. To do so issue
    the command

    QBASIX /u

    If you did load further programs in memory after QBASIC, it
    may not be able to erase itself from memory.

    Once loaded QBasiX TSR is ready for use. For the CALL ABSOLUTE
    however you need its address in memory. When QBasix TSR has
    ensconced itself in memory it reports the address it has got on
    screen. Now it would of course be very inconvenient if you
    should have to note that address all the time to be able to use
    it afterwards in your program. Fortunately something is done
    about that.

    In the QBASIX package you will find a file QBASIX.BAS. Its
    contents constitute a shell in which you can develop your own
    program. It includes a function named IsQBasix, which determines
    if QBasiX TSR is loaded and, if so, passes its address to the
    interface routines. This function is used in a programming
    framework that looks broadly as follows:

    IF NOT IsQBasix THEN
      PRINT "<error message>"
    ELSE
      ......
    END IF
    END

    Your own program has to be filled in at the place of the dots.

    The interface routines require the memory address of QBasiX TSR
    to trace the assembler routines, but of course they must also be
    able to indicate which assembler routine they want to get
    executed. Tot that end all assembler routines got a number,
    assigned to a constant with a obvious name. That name is similar
    as much as possible to the name of the interface routine in
    which it is used, preceded by a "c" (of "constant"). These
    constants you will find in QBASIX.BAS also.

    It is important that QBASIX.BAS begins with the basic command

    DEFINT A-Z

    The result of this command is that all variables, not explicitly
    having a type indication ($, %, &, !, #) in their name or being
    declared in a DIM command as of a certain type, are considered
    integers by QBASIC. Integers can be processed by the CPU much
    faster than floating point variables, the type of which is the
    default when no DEFINT or similar command is issued. Moreover
    they require much less machine instructions, resulting in more
    space in your program for other things.

    In order not to reserve memory for routines you don't use at all
    QBASIX' basic routines are included in a separate procedure file
    named QBASIX.PRO. From this you only have to copy the routines
    you really use. Pay attention to the fact that when using
    certain routines one or more of the other routines are required
    as well. Also do not forget to copy the declarations of
    variabele types and constants going with them. In every routine
    a comment indicates if QBasiX TSR assembler routines are used
    and by consequence QBASIX.EXE has to be loaded. It also
    indicates which other basic routines and variable types have to
    be included in your program to be able to use the routine at
    hand.

    Some new variable types are defined in QBASIX.PRO, They are:

    VideoType    The elements of this type refer to the video
            configuration. The required information is
            supplied by the GetVideoInfo routine

    RegTypeX    The elements of this type represent the relevant
            registers. This type is necessary when using the
            InterruptX and MSDOS interface routines. It is
            equal to the type of the same name defined by
            Microsoft in QB.BI.

    In addition to these, aside from the numbers of the assembler
    routines, a number of constants are defined. Two of them (TRUE
    and FALSE) are generally applicable, the other ones are useful
    when using certain routines. In the comment going with those
    routines your attention is drawn to them.

    In case you only use routines not requiring QBASIX.EXE, you
    of course don't need the program framework included in
    QBASIX.BAS as well.


    4. Using QBASIX with QuickBasic 4.0 and 4.5
    -------------------------------------------

    QBasiX TSR can be used with QuickBasic 4.0 or 4.5 as well. In
    that case start QB with the QBABS quick library enclosed in the
    QBASIX package, as follows:

    QB /L QBABS

    or with any other quick library including CALL ABSOLUTE. An
    example is QB.QLB, shipped by Microsoft with QuickBasic 4.0 and
    4.5. If you use that one, you have their InterruptX procedure as
    well, so you do not have use QBASIX' routine of the same name.

    The commands for reading and changing the command line are not
    necessary in QB because QB already provides these possibilities
    itself.


    5. Something about segmented addresses
    --------------------------------------

    To several subroutines and functions a segmented address must be
    passed as a parameter. A segmented address points to a location
    in memory. When used in BASIC it mostly will be the location of
    a BASIC variable, but other memory locations can be referenced
    as well. Somewhere at the bottom of memory for instance the BIOS
    uses an area to store all sorts of information with respect to
    the satellite devices. Of course it is not advisable to make
    changes in the contents of memory outside the data area of the
    BASIC program, but reading it will be quite harmless.

    Returning to the segmented address: it consists of two parts, a
    segment value and a matching offset value. A segment is a part
    of memory 64 Kb in size that begins at an absolute address (with
    respect to the start of memory), that is a multiple of 16. Such
    an address also is called a paragraph boundary or segment
    boundary; a paragraph is a unit of 16 bytes. The segment value
    of an address is such a segment paragraph, but divided by 16.

    It is easiest to work in the hexadecimal system. A paragraph
    boundary in that case always ends with a zero and dividing by 16
    then simply results in removal of the zero. In this way the
    screen memory of a color adapter begins at segment &HB800, which
    is address &HB8000.

    In contrast to the segment that represents an absolute address
    (from the start of memory) the offset is a relative address.
    That is because this measures the number of bytes from a segment
    paragraph. Suppose we have a segmented address &H1E34:&H038A,
    than we can calculate the corresponding absolute address by
    adding the offset &H38A to the segment paragraph &H1E340. The
    result is &H1E7CA, that is decimal 124874. It will be clear that
    an absolute address can be represented by many different
    segmented addresses. Every segment paragraph less than 64 Kb
    below it can be used as a base. The just calculated address, for
    instance, can also be referenced as &H1E33:&H039A, or as
    &H1E7C:&H000A.

    The segmented address of a basic variable is obtained with the
    basic functions VARSEG for its segment and VARPTR for its
    offset. However, to obtain the offset of strings of variabele
    length you must use SADD (that is "StringADDress") in stead of
    VARPTR. The basic commands acting on a memory address, PEEK,
    POKE and CALL ABSOLUTE, only use the offset part. The segment
    has to be set previously with DEF SEG = <segment>. Ordinary
    basic variables (except arrays) are all located in the default
    data segment. Unless you did set another segment before, the
    default data segment does not need to be set, but it is safer to
    do it nevertheless. Anyway QBASIX assumes the segment is always
    been set, also in case the default data segment is concerned.
    The default data segment is set with the command DEF SEG as
    such.

    Both segment and offset can assume values from 0 to 65535
    inclusive. As far as size goes these numbers fit in an integer,
    although integers range from -32768 to 32767 inclusive.
    Therefore you can safely assign segments and offsets to integer
    variables, as long as you do not do calculations with them. If
    you want to do that you have to do it by way of long integers.

    More about the memory of a PC and the way it has to be
    approached you will find in Peter Nortons book "Inside the IBM
    PC Revised and Enlarged", published by Brady Books, a division
    of Simon & Schuster Inc.


    6. Using QBASIX together with certain software for system and
       task management
    -------------------------------------------------------------

    Below an outline is sketched of some situations in which QBasiX
    TSR does not function properly, and an indication is given of
    how to avoid the problem. This list certainly is not exhausting.
    It is based only on my own experiences so far.

    4DOS.COM
    --------
    If QBasiX TSR is loaded inside a secundary or lower 4DOS shell
    it has to be unloaded before returning to the parent shell.
    Otherwise it stays behind in memory inactively. When it is
    loaded low it also renders a part of memory useless for
    programs.
    COMMAND.COM does not pose this problem. However, in that case
    also it is better not to load QBasiX TSR low inside a secundary
    shell, because the memory available for programs decreases more
    or even much more than necessary for QBasiX TSR only.

    NORTON Commander with 4DOS.COM
    ------------------------------
    In case you use the NORTON Commander together with 4DOS.COM,
    QBasiX TSR does not function if you load it from inside the
    commander. Therefore load QBasiX TSR before you start the NORTON
    commander.

    DOSSHELL
    --------
    If QBasiX TSR is loaded high inside a DOSSHELL task by means of
    the switch /h, it has to be unloaded before termination of that
    task. Otherwise it stays behind in memory inactively. If, on the
    contrary, QBasiX TSR is loaded low or is loaded high with
    LOADHIGH, DOSSHELL takes care of unloading it.
    You can load QBasiX TSR before starting DOSSHELL without a
    problem. In that case it is available in every task started by
    DOSSHELL.

    DESQView
    --------
    If QBasiX TSR is loaded before starting DESQView SetError does
    not function inside DESQView. To have QBasiX TSR fully
    functioning inside DESQView it has to be loaded in a DESQView
    window.


    8. Conclusion
    -------------

    The full QBASIX package for QBASIC includes:

    - QBASIX.EXE: the TSR, the program for loading the assembler
      routines in memory;
    - QBASIX.BAS: the programming framework for using QBASIX;
    - QBASIX.PRO: the basic procedures of QBASIX together with their
      declarations of variable types and constants;
    - QBASIX.LST: a list of all procedures, grouped with respect to
      their area of operation;
    - QBASIX.DOC: documentation by procedure;
    - QBASIX.MAN: this manual;
    - QBABS.QLB en QBABS.LIB: a quick library and matching normal
      library for using QBASIX with QuickBasic 4.x.

    All these are collected in one zip file with the name
    QBASIX.ZIP.

    Let me know when you encounter an problem in using QBASIX. In
    case this is due to an error in the source code, I shall try to
    fix that error. I welcome constructive criticism and suggestions
    for improvement.

    You can reach me by mail at my home address:

    Hans Lunsing
    Klaproos 38
    2317 EL     LEIDEN
    The Netherlands

    and by electronic mail at address:

        Internet:        [e-mail]
        Fidonet:         2:281/607.214